/**
 ******************************************************************************
 * @file           : error_codes.h
 * @brief          : 通用错误码定义和错误处理工具
 ******************************************************************************
 * @attention
 *
 * 统一的错误处理系统，提供错误码定义、错误追踪、错误日志等功能
 * 
 * 设计原则：
 * - 分层错误码：通用层(0-99) + 模块层(100+)
 * - 可裁剪：通过宏控制日志和追踪功能
 * - 零开销：编译期优化，可完全禁用
 * - RTOS友好：支持线程安全选项
 * 
 * 参考标准：
 * - Linux Kernel errno (POSIX)
 * - STM32 HAL_StatusTypeDef
 * - 嵌入式系统最佳实践
 *
 ******************************************************************************
 */

#ifndef ERROR_CODES_H
#define ERROR_CODES_H

#ifdef __cplusplus
extern "C" {
#endif

/* Includes ------------------------------------------------------------------*/
#include <stdint.h>
#include <stdbool.h>

/* Exported types ------------------------------------------------------------*/

/**
 * @brief 错误码类型定义
 */
typedef int32_t ErrorCode_t;

/**
 * @brief 错误严重级别枚举
 */
typedef enum
{
    ERR_SEVERITY_NONE = 0,      /*!< 无错误 */
    ERR_SEVERITY_INFO,          /*!< 信息 */
    ERR_SEVERITY_WARNING,       /*!< 警告 */
    ERR_SEVERITY_ERROR,         /*!< 错误 */
    ERR_SEVERITY_CRITICAL       /*!< 严重错误 */
} ErrorSeverity_e;

/**
 * @brief 错误信息结构体
 */
typedef struct
{
    ErrorCode_t code;           /*!< 错误码 */
    const char *function;       /*!< 函数名称 */
    uint32_t line;              /*!< 行号 */
    uint32_t timestamp;         /*!< 时间戳(ms) */
} ErrorInfo_t;

/* Exported constants --------------------------------------------------------*/

/* ============================================================================
 * 通用错误码定义 (0-99: 系统级通用错误)
 * ========================================================================= */

#define ERR_OK                      0       /*!< 成功 */

/* 参数错误 (1-19) */
#define ERR_NULL_POINTER            1       /*!< 空指针错误 */
#define ERR_INVALID_PARAM           2       /*!< 无效参数 */
#define ERR_OUT_OF_RANGE            3       /*!< 参数超出范围 */
#define ERR_BUFFER_TOO_SMALL        4       /*!< 缓冲区太小 */
#define ERR_INVALID_STATE           5       /*!< 无效状态 */

/* 资源错误 (20-39) */
#define ERR_NO_MEMORY               20      /*!< 内存不足 */
#define ERR_NO_RESOURCE             21      /*!< 资源不足 */
#define ERR_BUSY                    22      /*!< 设备忙 */
#define ERR_TIMEOUT                 23      /*!< 超时 */
#define ERR_NOT_READY               24      /*!< 设备未就绪 */

/* 操作错误 (40-59) */
#define ERR_NOT_INITIALIZED         40      /*!< 未初始化 */
#define ERR_ALREADY_INITIALIZED     41      /*!< 已初始化 */
#define ERR_NOT_SUPPORTED           42      /*!< 不支持的操作 */
#define ERR_PERMISSION_DENIED       43      /*!< 权限拒绝 */
#define ERR_OVERFLOW                44      /*!< 溢出 */
#define ERR_UNDERFLOW               45      /*!< 下溢 */

/* 硬件错误 (60-79) */
#define ERR_HARDWARE_FAULT          60      /*!< 硬件故障 */
#define ERR_IO_ERROR                61      /*!< I/O错误 */
#define ERR_CRC_ERROR               62      /*!< CRC校验错误 */
#define ERR_CHECKSUM_ERROR          63      /*!< 校验和错误 */

/* 通信错误 (80-99) */
#define ERR_COMM_ERROR              80      /*!< 通信错误 */
#define ERR_NO_RESPONSE             81      /*!< 无响应 */
#define ERR_PROTOCOL_ERROR          82      /*!< 协议错误 */

/* ============================================================================
 * 模块专用错误码 (100+: 各模块自定义，每个模块预留20个错误码)
 * 
 * 排列顺序：由浅入深、常用到不常用
 * - 基础外设 (100-199): GPIO/UART/I2C/SPI/Timer等
 * - 存储设备 (200-299): EEPROM/Flash/SD卡/文件系统
 * - 高级外设 (300-399): ADC/DAC/DMA/RTC/Display
 * - 通信协议 (400-459): CAN/USB/Network
 * - 应用模块 (460+): 用户自定义
 * ========================================================================= */

/* ===== 基础外设 (100-199) ===== */

/* UART模块错误 (100-119) */
#define ERR_UART_BASE               100
#define ERR_UART_TIMEOUT            (ERR_UART_BASE + 0)     /*!< UART超时 */
#define ERR_UART_OVERRUN            (ERR_UART_BASE + 1)     /*!< UART溢出 */
#define ERR_UART_FRAME_ERROR        (ERR_UART_BASE + 2)     /*!< UART帧错误 */
#define ERR_UART_PARITY_ERROR       (ERR_UART_BASE + 3)     /*!< UART校验错误 */

/* I2C模块错误 (120-139) */
#define ERR_I2C_BASE                120
#define ERR_I2C_TIMEOUT             (ERR_I2C_BASE + 0)      /*!< I2C超时 */
#define ERR_I2C_NACK                (ERR_I2C_BASE + 1)      /*!< I2C未应答 */
#define ERR_I2C_BUS_ERROR           (ERR_I2C_BASE + 2)      /*!< I2C总线错误 */

/* SPI模块错误 (140-159) */
#define ERR_SPI_BASE                140
#define ERR_SPI_TIMEOUT             (ERR_SPI_BASE + 0)      /*!< SPI超时 */
#define ERR_SPI_BUSY                (ERR_SPI_BASE + 1)      /*!< SPI忙 */
#define ERR_SPI_CRC_ERROR           (ERR_SPI_BASE + 2)      /*!< SPI CRC错误 */

/* Timer模块错误 (160-179) */
#define ERR_TIMER_BASE              160
#define ERR_TIMER_NOT_STARTED       (ERR_TIMER_BASE + 0)    /*!< 定时器未启动 */
#define ERR_TIMER_OVERFLOW          (ERR_TIMER_BASE + 1)    /*!< 定时器溢出 */

/* DMA模块错误 (180-199) */
#define ERR_DMA_BASE                180
#define ERR_DMA_TRANSFER_ERROR      (ERR_DMA_BASE + 0)      /*!< DMA传输错误 */
#define ERR_DMA_TIMEOUT             (ERR_DMA_BASE + 1)      /*!< DMA超时 */
#define ERR_DMA_BUSY                (ERR_DMA_BASE + 2)      /*!< DMA忙 */

/* ===== 存储设备 (200-299) ===== */

/* EEPROM模块错误 (200-219) */
#define ERR_EEPROM_BASE             200
#define ERR_EEPROM_WRITE_FAIL       (ERR_EEPROM_BASE + 0)   /*!< EEPROM写入失败 */
#define ERR_EEPROM_READ_FAIL        (ERR_EEPROM_BASE + 1)   /*!< EEPROM读取失败 */
#define ERR_EEPROM_VERIFY_FAIL      (ERR_EEPROM_BASE + 2)   /*!< EEPROM验证失败 */
#define ERR_EEPROM_CORRUPTED        (ERR_EEPROM_BASE + 3)   /*!< EEPROM数据损坏 */
#define ERR_EEPROM_TIMEOUT          (ERR_EEPROM_BASE + 4)   /*!< EEPROM操作超时 */

/* Flash模块错误 (220-239) */
#define ERR_FLASH_BASE              220
#define ERR_FLASH_WRITE_FAIL        (ERR_FLASH_BASE + 0)    /*!< Flash写入失败 */
#define ERR_FLASH_ERASE_FAIL        (ERR_FLASH_BASE + 1)    /*!< Flash擦除失败 */
#define ERR_FLASH_PROTECTED         (ERR_FLASH_BASE + 2)    /*!< Flash写保护 */
#define ERR_FLASH_VERIFY_FAIL       (ERR_FLASH_BASE + 3)    /*!< Flash验证失败 */

/* SD卡模块错误 (240-259) */
#define ERR_SD_BASE                 240
#define ERR_SD_NOT_PRESENT          (ERR_SD_BASE + 0)       /*!< SD卡未插入 */
#define ERR_SD_INIT_FAIL            (ERR_SD_BASE + 1)       /*!< SD卡初始化失败 */
#define ERR_SD_READ_FAIL            (ERR_SD_BASE + 2)       /*!< SD卡读取失败 */
#define ERR_SD_WRITE_FAIL           (ERR_SD_BASE + 3)       /*!< SD卡写入失败 */

/* 文件系统错误 (260-279) */
#define ERR_FS_BASE                 260
#define ERR_FS_NOT_MOUNTED          (ERR_FS_BASE + 0)       /*!< 文件系统未挂载 */
#define ERR_FS_FILE_NOT_FOUND       (ERR_FS_BASE + 1)       /*!< 文件未找到 */
#define ERR_FS_WRITE_FAIL           (ERR_FS_BASE + 2)       /*!< 文件写入失败 */
#define ERR_FS_READ_FAIL            (ERR_FS_BASE + 3)       /*!< 文件读取失败 */
#define ERR_FS_NO_SPACE             (ERR_FS_BASE + 4)       /*!< 磁盘空间不足 */

/* ===== 高级外设 (300-399) ===== */

/* ADC模块错误 (300-319) */
#define ERR_ADC_BASE                300
#define ERR_ADC_CONVERSION_FAIL     (ERR_ADC_BASE + 0)      /*!< ADC转换失败 */
#define ERR_ADC_CALIBRATION_FAIL    (ERR_ADC_BASE + 1)      /*!< ADC校准失败 */
#define ERR_ADC_TIMEOUT             (ERR_ADC_BASE + 2)      /*!< ADC转换超时 */

/* DAC模块错误 (320-339) */
#define ERR_DAC_BASE                320
#define ERR_DAC_OUTPUT_FAIL         (ERR_DAC_BASE + 0)      /*!< DAC输出失败 */
#define ERR_DAC_CALIBRATION_FAIL    (ERR_DAC_BASE + 1)      /*!< DAC校准失败 */

/* RTC模块错误 (340-359) */
#define ERR_RTC_BASE                340
#define ERR_RTC_NOT_INITIALIZED     (ERR_RTC_BASE + 0)      /*!< RTC未初始化 */
#define ERR_RTC_INVALID_TIME        (ERR_RTC_BASE + 1)      /*!< RTC时间无效 */

/* 显示模块错误 (360-379) */
#define ERR_DISPLAY_BASE            360
#define ERR_DISPLAY_INIT_FAIL       (ERR_DISPLAY_BASE + 0)  /*!< 显示器初始化失败 */
#define ERR_DISPLAY_TIMEOUT         (ERR_DISPLAY_BASE + 1)  /*!< 显示器超时 */

/* ===== 通信协议 (400-459) ===== */

/* CAN模块错误 (400-419) */
#define ERR_CAN_BASE                400
#define ERR_CAN_TIMEOUT             (ERR_CAN_BASE + 0)      /*!< CAN超时 */
#define ERR_CAN_BUS_OFF             (ERR_CAN_BASE + 1)      /*!< CAN总线关闭 */
#define ERR_CAN_ERROR_WARNING       (ERR_CAN_BASE + 2)      /*!< CAN错误警告 */
#define ERR_CAN_ERROR_PASSIVE       (ERR_CAN_BASE + 3)      /*!< CAN错误被动 */

/* USB模块错误 (420-439) */
#define ERR_USB_BASE                420
#define ERR_USB_NOT_CONNECTED       (ERR_USB_BASE + 0)      /*!< USB未连接 */
#define ERR_USB_TIMEOUT             (ERR_USB_BASE + 1)      /*!< USB超时 */
#define ERR_USB_TRANSFER_ERROR      (ERR_USB_BASE + 2)      /*!< USB传输错误 */

/* 网络模块错误 (440-459) */
#define ERR_NET_BASE                440
#define ERR_NET_NOT_CONNECTED       (ERR_NET_BASE + 0)      /*!< 网络未连接 */
#define ERR_NET_TIMEOUT             (ERR_NET_BASE + 1)      /*!< 网络超时 */
#define ERR_NET_DNS_FAIL            (ERR_NET_BASE + 2)      /*!< DNS解析失败 */
#define ERR_NET_SOCKET_ERROR        (ERR_NET_BASE + 3)      /*!< Socket错误 */

/* ===== 应用模块 (460+) ===== */

/* 传感器模块错误 (460-479) */
#define ERR_SENSOR_BASE             460
#define ERR_SENSOR_FAULT            (ERR_SENSOR_BASE + 0)   /*!< 传感器故障 */
#define ERR_SENSOR_OUT_OF_RANGE     (ERR_SENSOR_BASE + 1)   /*!< 传感器超出范围 */
#define ERR_SENSOR_TIMEOUT          (ERR_SENSOR_BASE + 2)   /*!< 传感器超时 */

/* 
 * 用户自定义错误码从 480 开始
 * 建议每个模块预留20个错误码
 */

/* Exported macro ------------------------------------------------------------*/

/* ============================================================================
 * 错误处理配置
 * ========================================================================= */

/**
 * @brief 是否启用错误日志功能
 * 
 * @note 启用后会记录错误历史，占用约256字节RAM
 *       禁用后可节省内存，但无法追踪错误历史
 */
#ifndef ERROR_LOG_ENABLED
#define ERROR_LOG_ENABLED           1
#endif

/**
 * @brief 错误日志最大条目数
 * 
 * @note 使用循环缓冲区，旧的记录会被新记录覆盖
 */
#ifndef ERROR_LOG_MAX_ENTRIES
#define ERROR_LOG_MAX_ENTRIES       16
#endif

/**
 * @brief 是否启用错误追踪功能
 * 
 * @note 启用后会记录函数名和行号，便于调试
 *       禁用后可减少代码空间
 */
#ifndef ERROR_TRACE_ENABLED
#define ERROR_TRACE_ENABLED         1
#endif

/* ============================================================================
 * 错误处理宏定义
 * ========================================================================= */

#if ERROR_TRACE_ENABLED
    /**
     * @brief 返回错误码并记录追踪信息
     */
    #define RETURN_ERROR(code) \
        do { \
            Error_Log((code), __func__, __LINE__); \
            return (code); \
        } while(0)
    
    /**
     * @brief 检查函数返回值，如果错误则记录并返回
     */
    #define CHECK_ERROR(expr) \
        do { \
            ErrorCode_t _err = (expr); \
            if (_err != ERR_OK) { \
                Error_Log(_err, __func__, __LINE__); \
                return _err; \
            } \
        } while(0)
#else
    /* 简化版（无追踪） */
    #define RETURN_ERROR(code)      return (code)
    
    #define CHECK_ERROR(expr) \
        do { \
            ErrorCode_t _err = (expr); \
            if (_err != ERR_OK) { \
                return _err; \
            } \
        } while(0)
#endif

/**
 * @brief 检查指针是否为NULL
 */
#define CHECK_NULL_POINTER(ptr) \
    do { \
        if ((ptr) == NULL) { \
            RETURN_ERROR(ERR_NULL_POINTER); \
        } \
    } while(0)

/**
 * @brief 检查参数条件
 */
#define CHECK_PARAM(condition) \
    do { \
        if (!(condition)) { \
            RETURN_ERROR(ERR_INVALID_PARAM); \
        } \
    } while(0)

/**
 * @brief 检查范围
 */
#define CHECK_RANGE(value, min, max) \
    do { \
        if ((value) < (min) || (value) > (max)) { \
            RETURN_ERROR(ERR_OUT_OF_RANGE); \
        } \
    } while(0)

/* Exported functions --------------------------------------------------------*/

/* 错误码工具函数 */
const char* Error_CodeToString(ErrorCode_t code);              /* 错误码转字符串 */
ErrorSeverity_e Error_GetSeverity(ErrorCode_t code);           /* 获取错误严重级别 */

/* 错误日志函数 */
void Error_Log(ErrorCode_t code, const char *function, uint32_t line);  /* 记录错误日志 */
const ErrorInfo_t* Error_GetLastError(void);                   /* 获取最后一次错误 */
void Error_ClearLog(void);                                     /* 清除错误日志 */
void Error_PrintLog(void);                                     /* 打印错误日志 */

/* 错误统计函数 */
uint32_t Error_GetCount(ErrorCode_t code);                     /* 获取特定错误出现次数 */
uint32_t Error_GetTotalCount(void);                            /* 获取总错误次数 */

#ifdef __cplusplus
}
#endif

#endif /* ERROR_CODES_H */
